Developer CD Series 1997 January: Mac OS SDK/Dev.CD Jan 97 SDK2.toast/Development Kits (Disc 2)/OpenDoc/Developer Documentation/Human Interface/Human Interface Q & A/HI Q& A #10

Text File | 1996-04-26 | 9.1 KB | 198 lines | [ttro/ttxt]

Q&A #10
Scripting, Buttons, and Hypertext

By the Apple Computer OpenDoc Human Interface Team and Jon Pugh OpenDoc Engineering

As published in the January 1996 Apple Directions

This time we're going to focus on supporting scripting within OpenDoc. This
article doesn't address all the questions on scripting, so please send us
any others you think of; we'll answer them in future columns.

Q: How do you script actions like selecting a menu and other controls (such
as sliders)?

A: This might be a good time to briefly mention the different levels of
scripting support. If you want more details on scripting, see Chapter 9 in
the OpenDoc Programmer's Guide.

First, a part can be scriptable. To be scriptable, your part editor must
publish a list of its content objects (for example, lines and words in a
text part) and operations (for example, bold in a text part) and then accept
semantic events (for example, "Set Data to Bold"). For your part to be fully
scriptable, semantic events must be able to invoke any action a user might
be able to perform. Someone can then write a script to invoke the particular
user action.

The next level of scripting support is for your part to support recording.
If your part is recordable, it can capture the user's actions as a series of
semantic events, convert the actions to scripts, and replay them at a later
time to reenact the actions.

The final level of scripting support is to make your part's interface
customizable (sometimes referred to as being "tinkerable"). If your part is
customizable, users can invoke all the actions through scripts, and they can
change the behavior of the operations. To be customizable, the part editor
must be scriptable and must define content objects and operations for
interface elements such as menus and buttons.

Getting back to your question, your part's interface must be customizable to
support the actions you mention. We've said in a previous column (Apple
Directions, October 1995) that users may attach a script to a scriptable
part--for example, through the Settings dialog box. A script may have
multiple sections of script code (handlers) for the different operations
whose behavior you want to change. Suppose that you want your part to
support events such as mouseDown, mouseUp, mouseEnter, mouseLeave, and
pickMenuItem; when designing your part editor, you must define event names
for each operation that your editor will support. Before your editor
processes any event, the editor must check with the attached script to see
if it can handle the event. If so, that section of the script is run.

If you want to allow users to write scripts that control your part, you
should publish your list of event names in your part's documentation and
'aete' resource. Because HyperCard uses a set of event names for the common
actions a user might perform, you might want to look at HyperCard events as
examples to follow. By the way, HyperCard uses the subroutine event to
implement many of its events. For more details on subroutines, you may want
to look at the Developer Notes document on the AppleScript CD.

Q: What about scripting document-level commands such as Open, Close, and
Print? What do I have to do?

A: There are operations that relate to the entire document--for example,
closing, saving, and printing the current document, or opening a different
document. The OpenDoc shell handles three of the four required events (the
fourth, Open Application, does not apply in the OpenDoc environment). Your
part editor can override the definitions of these events. Note that
definitions of these events are slightly different than in today's
applications:

   • Quit--close all windows of the document
   • Print--print the active window
   • Open--open the specified document

The OpenDoc shell also supports three of the core events, which your editor
may override. The events are

   • Close--close the active window
   • Save--save the current document
   • Save As--save a copy of the current document into a new document

The OpenDoc shell will first determine if the editor of the root part
implements these commands; otherwise, the shell provides the default
implementation.

In addition, if the user wishes to attach a script that is to be executed
for one of these events, they must be attached to the root part of the
document.

Q: How should a script identify parts within a document?

A: This can be very tricky for any document that can be revised, because
parts need not be named or have unique names. Furthermore, the index of a
part may vary over time, and different parts will have different ways of
indexing their contents. For example, "line 3" is fairly obvious; "circle 3"
is not. Therefore, the only reliable way to refer to a part is by its ID.
Unfortunately, the ID is not a very user-friendly or visible number;
however, the user can always find the ID of a part through the Part Info
dialog box.

This problem isn't unique to OpenDoc, or even to AppleScript. There just
doesn't seem to be a great solution to this problem.

Q: In a previous column, you said that parts should place their scripts in
the Settings dialog box. Doesn't that force parts to provide some
text-editing capability to edit scripts?

A: Yes--to allow users to edit the script, your part needs to provide some
mechanism for viewing and editing the script. For a text-based language,
that means you need to support text editing. (Remember that some script
languages may have a representation other than text.) The text editor you
provide can just be a simple multiline edit control. For the future, we are
looking at providing a scripting service that parts could use.

Q: I want to create a "button" that really is an embedded graphic in a
container part--like having a picture in a HyperCard stack. When the user
clicks the "button," the container part will run some script. In other
words, the graphic part does not support scripting, but its container
provides the scripting for the embedded part and gives it button-like
behavior. Any suggestions?

A: The basic rule in OpenDoc is that a click goes through to the smallest
part containing the mouse pointer. So, if the user clicks on the graphic,
that part would get the click. But in your example you want the container to
get the click and handle it. To do this you need to "fake out" the embedded
part so that it doesn't get the click, but the container does.

There is one easy way to get around this problem. If a part is "bundled,"
then it doesn't get the click--its container does. So, the container could
always set the bundled checkbox (in the Part Info dialog box) for all parts
that are embedded within that container.

Whenever the user clicks the graphic part, the container part would get the
click, determine which "button" was clicked, and then run the appropriate
script.

This all makes sense when the part is in "run" mode. However, you need to
allow the user to edit the buttons as well. If you have "run" and "edit"
modes, you should turn the bundle property off--otherwise, the user can't
edit the picture of the button.

Important: Our guidelines recommend that the user should be the only one who
turns the bundled checkbox on or off. But this example is a case in which
the container part could set the bundle property.

Q: How does one avoid modes when editing buttons?

A: Modes aren't always a bad thing--we work in different modes all the time.
Modes are bad when they aren't clearly visible. So, a mode for editing a
script, editing the name of a button, or resizing a part should be clearly
distinct from other modes in which the user could be working.

Attributes such as button name, size, and color are properties of the
button, and you can place them in the Settings dialog box. Even though
setting attributes is a mode, the mode is clearly visible and distinct.

Sometimes your users may need "edit" and "run" modes. For example, imagine
using a part builder to make frequent and numerous property changes. If the
part required you to bring up the Settings dialog box every time you wanted
to add or change a part, after awhile you'd probably want an easier and
faster way to enter these changes directly--an "edit" mode. These builder
applications really need the two modes, because the modes really reflect two
different user tasks. They are long-term modes, and as long as they are
clearly visible and distinct from one another, using them should be clear to
the user.

Q: How is hypertext achieved in OpenDoc? I see a couple of ways to do this:
Embed a button in the text part or make hypertext a "style." Which method
would you suggest?

A: In the 1.0 release of OpenDoc, we have no specific support for hypertext
links. We know this is an important issue and plan to work on it for a
future release. Right now, any approach will have the same major problem:
namely, OpenDoc does not provide any mechanism to display any destination of
a hypertext link smaller than a part. For example, there is no way to create
a link to a particular paragraph in a text part, or a particular portion of
a picture.

We are interested in hearing any suggestions you have.
__________________________________________________________

Copyright (c) 1995 by Apple Computer, Inc. All Rights Reserved.